home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 1.iso / toolbox / documents / Dwarf / libdwarf2p.1.mm < prev    next >
Text File  |  1996-11-11  |  47KB  |  1,163 lines
  1. \." $Revision: 1.1 $
  2. \." $Date: 1996/03/17 23:17:39 $
  3. \."
  4. \."
  5. \." the following line may be removed if the ff ligature works on your machine
  6. .lg 0
  7. \." set up heading formats
  8. .ds HF 3 3 3 3 3 2 2
  9. .ds HP +2 +2 +1 +0 +0
  10. .nr Hs 5
  11. .nr Hb 5
  12. .ds | |
  13. .ds ~ ~
  14. .ds ' '
  15. .if t .ds Cw \&\f(CW
  16. .if n .ds Cw \fB
  17. .de Cf          \" Place every other arg in Cw font, beginning with first
  18. .if \\n(.$=1 \&\*(Cw\\$1\fP
  19. .if \\n(.$=2 \&\*(Cw\\$1\fP\\$2
  20. .if \\n(.$=3 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP
  21. .if \\n(.$=4 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4
  22. .if \\n(.$=5 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP
  23. .if \\n(.$=6 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6
  24. .if \\n(.$=7 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP
  25. .if \\n(.$=8 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8
  26. .if \\n(.$=9 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8\
  27. *(Cw
  28. ..
  29. .SA 1
  30. .TL
  31. A Producer Library Interface to DWARF
  32. .AF ""
  33. .AU "UNIX\(rg International Programming Languages Special Interest Group" 
  34. .PF "'$Revision: 1.1 $'- \\\\nP -'$Date: 1996/03/17 23:17:39 $'"
  35. .PM ""
  36. .AS 1
  37. This document describes a proposed interface to a library of functions
  38. .FS \(rg
  39. UNIX is a registered trademark of UNIX System Laboratories, Inc.
  40. in the United States and other countries.
  41. .FE
  42. to create DWARF debugging information entries and DWARF line number
  43. information. It does not make recommendations as to how the functions
  44. described in this document should be implemented nor does it
  45. suggest possible optimizations. 
  46. .P
  47. The document is oriented to creating DWARF version 2.
  48. It will be proposed to the PLSIG DWARF committee as soon
  49. as that makes any sense.
  50. .P
  51. No proposals like this have ever been submitted to the PLSIG
  52. committee....
  53. .P
  54. The proposals made in this document are subject to change.
  55. .P
  56. $Revision: 1.1 $
  57. $Date: 1996/03/17 23:17:39 $
  58. .AE
  59. .MT 4
  60. .H 1 "INTRODUCTION"
  61. This document describes the proposed interface to \fIlibdwarf\fP, a
  62. library of functions to provide creation of DWARF debugging information
  63. records, DWARF line number information, DWARF address range and
  64. pubnames information, weak names informatio, and DWARF frame description 
  65. information.
  66.  
  67. .H 2 "Purpose and Scope"
  68. The purpose of this document is to propose a library of functions to 
  69. create DWARF debugging information.  Reading (consuming) of such records 
  70. is discussed in a separate document.
  71.  
  72. The functions in this document have been implemented at Silicon Graphics
  73. and are being used by the code generator to provide debugging information.
  74.  
  75. .P
  76. Additionally, the focus of this document is the functional interface,
  77. and as such, implementation as well as optimization issues are
  78. intentionally ignored.
  79.  
  80. .P
  81. Error handling, error codes, and certain \fILibdwarf\fP codes are discussed
  82. in the "\fIProposed Interface to DWARF Consumer Library\fP", which should 
  83. be read (or at least skimmed) before reading this document.
  84.  
  85. .H 2 "Definitions"
  86. DWARF debugging information entries (DIE) are the segments of information 
  87. placed in the \f(CW.debug_*\fP sections by compilers, assemblers, and linkage 
  88. editors that, in conjunction with line number entries, are necessary for 
  89. symbolic source-level debugging.  Refer to the document 
  90. "\fIDWARF Debugging Information Format\fP" from UI PLSIG for a more complete 
  91. description of these entries.
  92.  
  93. .P
  94. This document adopts all the terms and definitions in
  95. "\fIDWARF Debugging Information Format\fP" version 2.
  96. and the "\fIProposed Interface to DWARF Consumer Library\fP".
  97.  
  98. .P
  99. In addition, this document refers to ELF, the ATT/USL System V
  100. Release 4 object format.
  101. This is because the library was first developed for that object
  102. format.
  103. Hopefully the functions defined here can easily be
  104. applied to other object formats.
  105.  
  106. .H 2 "Overview"
  107. The remaining sections of this document describe a proposed producer 
  108. (compiler or assembler) interface to \fILibdwarf\fP, first by describing 
  109. the purpose of additional types defined by the interface, followed by 
  110. descriptions of the available operations.  This document assumes you 
  111. are thoroughly familiar with the information contained in the \fIDWARF 
  112. Debugging Information Format\fP document, and 
  113. "\fIProposed Interface to DWARF Consumer Library\fP".
  114.  
  115. .P
  116. The interface necessarily knows a little bit about the object format
  117. (which is assumed to be ELF).  We make an attempt to make this knowledge 
  118. as limited as possible.  For example, \fILibdwarf\fP does not do the 
  119. writing of object data to the disk.  The producer program does that.
  120.  
  121. .H 2 "Revision History"
  122. .VL 15
  123. .LI "March 93"
  124. Work on dwarf2 sgi producer draft begins
  125. .LE
  126.  
  127. .H 1 "Type Definitions"
  128.  
  129. .H 2 "General Description"
  130. The \fIlibdwarf.h\fP header file contains typedefs and preprocessor 
  131. definitions of types and symbolic names used to reference objects of 
  132. \fILibdwarf\fP.  The types defined by typedefs contained in \fIlibdwarf.h\fP 
  133. all use the convention of adding \f(CWDwarf_\fP as a prefix to
  134. indicate that they refer to objects used by Libdwarf.  The prefix
  135. \f(CWDwarf_P_\fP is used for object referenced by the \f(CWLibdwarf\fP 
  136. Producer when there are similar but distinct objects used by the Consumer.
  137.  
  138. .H 2 "Aggregate Types"
  139.  
  140. .H 1 "Memory Management"
  141.  
  142. Several of the functions that comprise the \fILibdwarf\fP interface 
  143. return values that have been dynamically allocated by the library.  
  144. Space is always allocated for an object represented by a 
  145. \f(CWDwarf_P_Debug\fP descriptor.  The \f(CWLibdwarf\fP typically 
  146. deals with one object at a time.  The dynamically allocated spaces 
  147. can not be reclaimed except by \f(CWdwarf_producer_finish()\fP.  
  148. This function reclaims all the space, and invalidates all descriptors 
  149. returned from \f(CWLibdwarf\fP functions that add information to be 
  150. object specified.  After \f(CWdwarf_producer_finish()\fP is called, 
  151. the \f(CWDwarf_P_Debug\fP descriptor specified is also invalid.
  152.  
  153. .H 2 "Read-only Properties"
  154. All pointers returned by or as a result of a \fILibdwarf\fP call should 
  155. be assumed to point to read-only memory.  
  156. Except as defined by this document, the results are undefined for 
  157. \fILibdwarf\fP clients that attempt to write to a region pointed to by a 
  158. return value from a \fILibdwarf\fP call.
  159.  
  160. .H 2 "Storage Deallocation"
  161. Calling \f(CWdwarf_producer_finish(dbg)\fP frees all the space, and 
  162. invalidates all pointers returned from \f(CWLibdwarf\fP functions on 
  163. or descended from \f(CWdbg\fP).
  164.  
  165. .H 1 "Functional Interface"
  166. This section describes the functions available in the \fILibdwarf\fP
  167. library.  Each function description includes its definition, followed 
  168. by a paragraph describing the function's operation.
  169.  
  170. .P
  171. The functions may be categorized into groups: 
  172. \fIinitialization and termination operations\fP,
  173. \fIdebugging information entry creation\fP,
  174. \fIElf section callback function\fP,
  175. \fIattribute creation\fP,
  176. \fIexpression creation\fP, 
  177. \fIline number creation\fP, 
  178. \fIfast-access (aranges) creation\fP, 
  179. \fIfast-access (pubnames) creation\fP, 
  180. \fIfast-access (weak names) creation\fP,
  181. \fImacro information creation\fP, 
  182. \fIlow level (.debug_frame) creation\fP, 
  183. and
  184. \fIlocation list (.debug_loc) creation\fP. 
  185.  
  186. .P
  187. The following sections describe these functions.
  188.  
  189. .H 2 "Initialization and Termination Operations"
  190. These functions setup \f(CWLibdwarf\fP to accumulate debugging information
  191. for an object, usually a compilation-unit, provided by the producer.
  192. The actual addition of information is done by functions in the other
  193. sections of this document.  Once all the information has been added,
  194. functions from this section are used to transform the information to
  195. appropriate byte streams, and help to write out the byte streams to
  196. disk.
  197.  
  198. Typically then, a producer would create a \f(CWDwarf_P_Debug\fP 
  199. descriptor to gather debugging information for a particular
  200. compilation-unit using \f(CWdwarf_producer_init()\fP.  They would 
  201. use this \f(CWDwarf_P_Debug\fP descriptor to accumulate debugging 
  202. information for this object using functions from other sections of 
  203. this document.  Once all the information had been added, they would 
  204. call \f(CWdwarf_transform_to_disk_form()\fP to convert the accumulated 
  205. information into byte streams in accordance with the \f(CWDWARF\fP 
  206. standard.  They would then repeatedly call \f(CWdwarf_get_section_bytes()\fP 
  207. for each of the \f(CW.debug_*\fP created.  This would give the producer 
  208. information about the data bytes to be written to disk.  At this point, 
  209. the producer would release all resource used by \f(CWLibdwarf\fP for 
  210. this object by calling \f(CWdwarf_producer_finish()\fP.
  211.  
  212. .DS
  213. \f(CWDwarf_P_Debug dwarf_producer_init(
  214.         Dwarf_Unsigned flags,
  215.         Dwarf_Callback_Func func,
  216.         Dwarf_Handler errhand,
  217.         Dwarf_Ptr errarg,
  218.         Dwarf_Error *error)\fP
  219. .DE
  220. The function \f(CWdwarf_producer_init()\fP returns a new 
  221. \f(CWDwarf_P_Debug\fP descriptor that can be used to add \f(CWDwarf\fP 
  222. information to the object.  On error it returns \f(CWDW_DLV_BADADDR\fP.  
  223. \f(CWflags\fP determine whether the target object is 64-bit or 32-bit.  
  224. \f(CWfunc\fP is a pointer to a function called-back from \fILibdwarf\fP 
  225. whenever \fILibdwarf\fP needs to create a new object section (as it will 
  226. for each .debug_* section and related relocation section).  \f(CWerrhand\fP 
  227. is a pointer to a function that will be used for handling errors detected 
  228. by \f(CWLibdwarf\fP.  \f(CWerrarg\fP is the default error argument used 
  229. by the function pointed to by \f(CWerrhand\fP.
  230. .P
  231. The function \f(CWfunc\fP 
  232. must be provided by the user of this library.
  233. Its prototype is:
  234. .DS
  235. \f(CWtypedef int (*Dwarf_Callback_Func)(char* name,
  236.     int                 size,
  237.     Dwarf_Unsigned      type,
  238.     Dwarf_Unsigned      flags,
  239.     Dwarf_Unsigned      link,
  240.     Dwarf_Unsigned      info,
  241.     int*                sect_name_index,
  242.     int*                error);\fP
  243. .DE
  244. For each section in the object file that \f(CWlibdwarf\fP
  245. needs to create, it calls this function once, passing in
  246. the section \f(CWname\fP, the section \f(CWtype\fP,
  247. the section \f(CWflags\fP, the \f(CWlink\fP field, and
  248. the \f(CWinfo\fP field.  For an ELF object file these values
  249. should be appropriate ELF section header values.
  250. On success
  251. the user function should return the ELF section number of the
  252. newly created ELF section on success.
  253. .P
  254. On success, the function should also set the integer
  255. pointed to by \f(CWsect_name_index\fP to the
  256. ELF symbol number assigned in the ELF symbol table of the
  257. new ELF section.
  258. This symbol number is needed with relocations
  259. dependent on the relocation of this new section.
  260. .P
  261. For example, the \f(CW.debug_line\fP section's third
  262. data element (in a compilation unit) is the offset from the
  263. beginning of the \f(CW.debug_info\fP section of the compilation
  264. unit entry for this \f(CW.debug_line\fP set.
  265. The relocation entry in \f(CW.rel.debug_line\fP
  266. for this offset
  267. must have the relocation symbol index of the 
  268. symbol \f(CW.debug_info\fP  returned
  269. by the callback of that section-creation through 
  270. the pointer \f(CWsect_name_index\fP.
  271. .P
  272. On failure, the function should return -1 and set the \f(CWerror\fP
  273. integer to an error code.
  274. .DS
  275. \f(CWDwarf_Signed dwarf_transform_to_disk_form(
  276.         Dwarf_P_Debug dbg,
  277.         Dwarf_Error* error)\fP
  278. .DE
  279. The function \f(CWdwarf_transform_to_disk_form()\fP does the actual
  280. conversion of the \f(CWDwarf\fP information provided so far, to the
  281. form that is 
  282. normally written out as \f(CWElf\fP sections.  In other words, 
  283. once all DWARF information has been passed to \fILibdwarf\fP, call 
  284. \f(CWdwarf_transform_to_disk_form()\fP to transform all the accumulated 
  285. data into byte streams.  This includes turning relocation information 
  286. into byte streams.  This function does not write anything to disk.  If 
  287. successful, it returns a count of the number of \f(CWElf\fP sections 
  288. ready to be retrieved (and, normally, written to disk).
  289. In case of error, it returns 
  290. \f(CWDW_DLV_NOCOUNT\fP.
  291.  
  292. .DS
  293. \f(CWDwarf_Ptr dwarf_get_section_bytes(
  294.         Dwarf_P_Debug dbg,
  295.         Dwarf_Signed dwarf_section,
  296.         Dwarf_Signed *elf_section_index, 
  297.         Dwarf_Unsigned *length,
  298.         Dwarf_Error* error)\fP
  299. .DE
  300. The function \f(CWdwarf_get_section_bytes()\fP must be called repetitively, 
  301. with the index \f(CWdwarf_section\fP starting at 0 and continuing for the 
  302. number of sections returned by \f(CWdwarf_transform_to_disk_form()\fP.
  303. It returns \f(CWNULL\fP to indicate that there are no more sections of 
  304. \f(CWDwarf\fP information.  For each non-NULL return, the returned-pointer
  305. points to \f(CW*length\fP bytes of data that are normally
  306. added to the output 
  307. object in \f(CWElf\fP section \f(CW*elf_section\fP by the producer application.
  308.  
  309. .DS
  310. \f(CWDwarf_Signed dwarf_producer_finish(
  311.         Dwarf_P_Debug dbg,
  312.         Dwarf_Error* error)\fP
  313. .DE
  314. The function \f(CWdwarf_producer_finish()\fP should be called after all 
  315. the bytes of data have been wn copied somewhere
  316. (normally the bytes are written to disk).  It frees all dynamic space 
  317. allocated for \f(CWdbg\fP, include space for the structure pointed to by
  318. \f(CWdbg\fP.  This should not be called till the data have been 
  319. copied or written 
  320. to disk or are no longer of interest.  
  321. It returns non-zero if successful, and \f(CWDW_DLV_NOCOUNT\fP 
  322. if there is an error.
  323.  
  324. .H 2 "Debugging Information Entry Creation"
  325. The functions in this section add new \f(CWDIE\fPs to the object,
  326. and also the relatioships among the \f(CWDIE\fP to be specified
  327. by linking them up as parents, children, left or right siblings
  328. of each other.  In addition, there is a function that marks the
  329. root of the graph thus created.
  330.  
  331. .DS
  332. \f(CWDwarf_Unsigned dwarf_add_die_to_debug(
  333.         Dwarf_P_Debug dbg,
  334.         Dwarf_P_Die first_die,
  335.         Dwarf_Error *error)\fP
  336. .DE
  337. The function \f(CWdwarf_add_die_to_debug()\fP indicates to \f(CWLibdwarf\fP
  338. the root \f(CWDIE\fP of the \f(CWDIE\fP graph that has been built so 
  339. far.  It is intended to mark the compilation-unit \f(CWDIE\fP for the 
  340. object represented by \f(CWdbg\fP.  The root \f(CWDIE\fP is specified 
  341. by \f(CWfirst_die\fP.
  342.  
  343. It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error.
  344.  
  345. .DS
  346. \f(CWDwarf_P_Die dwarf_new_die(
  347.         Dwarf_P_Debug dbg, 
  348.         Dwarf_Tag new_tag,
  349.         Dwarf_P_Die parent,
  350.         Dwarf_P_Die child,
  351.         Dwarf_P_Die left_sibling, 
  352.         Dwarf_P_Die right_sibling,
  353.         Dwarf_Error *error)\fP
  354. .DE
  355. The function \f(CWdwarf_new_die()\fP creates a new \f(CWDIE\fP with
  356. its parent, child, left sibling, and right sibling \f(CWDIE\fPs
  357. specified by \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP,
  358. and \f(CWright_sibling\fP, respectively.  There is no requirement
  359. that all of these \f(CWDIE\fPs be specified, i.e. any of these
  360. descriptors may be \f(CWNULL\fP.  If none is specified, this will
  361. be an isolated \f(CWDIE\fP.  
  362. A \f(CWDIE\fP is 
  363. transformed to disk form by \f(CWdwarf_transform_to_disk_form()\fP 
  364. only if there is a path from
  365. the \f(CWDIE\fP specified by \f(CWdwarf_add_die_to_debug\fP to it.
  366. This function returns \f(CWDW_DLV_BADADDR\fP on error.
  367.  
  368. \f(CWnew_tag\fP is the tag which is given to the new \f(CWDIE\fP.
  369. \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP, and
  370. \f(CWright_sibling\fP are pointers to establish links to existing 
  371. \f(CWDIE\fPs.  Only one of \f(CWparent\fP, \f(CWchild\fP, 
  372. \f(CWleft_sibling\fP, and \f(CWright_sibling\fP may be non-NULL.
  373. If \f(CWparent\fP (\f(CWchild\fP) is given, the \f(CWDIE\fP is 
  374. linked into the list after (before) the \f(CWDIE\fP pointed to.  
  375. If \f(CWleft_sibling\fP (\f(CWright_sibling\fP) is given, the 
  376. \f(CWDIE\fP is linked into the list after (before) the \f(CWDIE\fP 
  377. pointed to.
  378.  
  379. To add attributes to the new \f(CWDIE\fP, use the \f(CWAttribute Creation\fP 
  380. functions defined in the next section.
  381.  
  382. .DS
  383. \f(CWDwarf_P_Die dwarf_die_link(
  384.         Dwarf_P_Die die, 
  385.         Dwarf_P_Die parent,
  386.         Dwarf_P_Die child,
  387.         Dwarf_P_Die left-sibling, 
  388.         Dwarf_P_Die right_sibling,
  389.         Dwarf_Error *error)\fP
  390. .DE
  391. The function \f(CWdwarf_die_link()\fP links an existing \f(CWDIE\fP
  392. described by the given \f(CWdie\fP to other existing \f(CWDIE\fPs.
  393. The given \f(CWdie\fP can be linked to a parent \f(CWDIE\fP, a child
  394. \f(CWDIE\fP, a left sibling \f(CWDIE\fP, or a right sibling \f(CWDIE\fP
  395. by specifying non-NULL \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP,
  396. and \f(CWright_sibling\fP \f(CWDwarf_P_Die\fP descriptors.  It returns
  397. the given \f(CWDwarf_P_Die\fP descriptor, \f(CWdie\fP, on success,
  398. and \f(CWDW_DLV_BADADDR\fP on error.
  399.  
  400. Only one of \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP,
  401. and \f(CWright_sibling\fP may be non-NULL.  If \f(CWparent\fP
  402. (\f(CWchild\fP) is given, the \f(CWDIE\fP is linked into the list 
  403. after (before) the \f(CWDIE\fP pointed to.  If \f(CWleft_sibling\fP
  404. (\f(CWright_sibling\fP) is given, the \f(CWDIE\fP is linked into 
  405. the list after (before) the \f(CWDIE\fP pointed to.  Non-NULL links
  406. overwrite the corresponding links the given \f(CWdie\fP may have
  407. had before the call to \f(CWdwarf_die_link()\fP.
  408.  
  409. .H 2 "Attribute Creation"
  410. The functions in this section add attributes to a \f(CWDIE\fP.
  411. These functions return a \f(CWDwarf_P_Attribute\fP descriptor 
  412. that represents the attribute added to the given \f(CWDIE\fP.  
  413. In most cases the return value is only useful to determine if 
  414. an error occurred.
  415.  
  416. Some of the attributes have values that are relocatable.  They
  417. need a symbol with respect to which the linker will perform
  418. relocation.  This symbol is specified by means of an index into
  419. the Elf symbol table for the object.
  420.  
  421. .DS
  422. \f(CWDwarf_P_Attribute dwarf_add_AT_location_expr(
  423.         Dwarf_P_Debug dbg,
  424.         Dwarf_P_Die ownerdie,
  425.         Dwarf_Half attr,
  426.         Dwarf_P_Expr loc_expr,
  427.         Dwarf_Error *error)\fP
  428. .DE
  429. The function \f(CWdwarf_add_AT_location_expr()\fP adds the attribute
  430. specified by \f(CWattr\fP to the \f(CWDIE\fP descriptor given by
  431. \f(CWownerdie\fP.  The attribute should be one that has a location
  432. expression as its value.  The location expression that is the value
  433. is represented by the \f(CWDwarf_P_Expr\fP descriptor \f(CWloc_expr\fP.
  434. It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
  435. given, on success.  On error it returns \f(CWDW_DLV_BADADDR\fP.
  436.  
  437. .DS
  438. \f(CWDwarf_P_Attribute dwarf_add_AT_name(
  439.         Dwarf_P_Die ownerdie, 
  440.         char *name,
  441.         Dwarf_Error *error)\fP
  442. .DE
  443. The function \f(CWdwarf_add_AT_name()\fP adds the string specified
  444. by \f(CWname\fP as the value of the \f(CWDW_AT_name\fP attribute
  445. for the given \f(CWDIE\fP, \f(CWownerdie\fP.  It returns the 
  446. \f(CWDwarf_P_attribute\fP descriptor for the \f(CWDW_AT_name\fP 
  447. attribute on success.  On error, it returns \f(CWDW_DLV_BADADDR\fP.
  448.  
  449. .DS
  450. \f(CWDwarf_P_Attribute dwarf_add_AT_comp_dir(
  451.         Dwarf_P_Die ownerdie,
  452.         char *current_working_directory,
  453.         Dwarf_Error *error)\fP
  454. .DE
  455. The function \f(CWdwarf_add_AT_comp_dir()\fP adds the string given by
  456. \f(CWcurrent_working_directory\fP as the value of the \f(CWDW_AT_comp_dir\fP
  457. attribute for the \f(CWDIE\fP described by the given \f(CWownerdie\fP.  
  458. It returns the \f(CWDwarf_P_Attribute\fP for this attribute on success.
  459. On error, it returns \f(CWDW_DLV_BADADDR\fP.
  460.  
  461. .DS
  462. \f(CWDwarf_P_Attribute dwarf_add_AT_producer(
  463.         Dwarf_P_Die ownerdie,
  464.         char *producer_string,
  465.         Dwarf_Error *error)\fP
  466. .DE
  467. The function \f(CWdwarf_add_AT_producer()\fP adds the string given by
  468. \f(CWproducer_string\fP as the value of the \f(CWDW_AT_producer\fP
  469. attribute for the \f(CWDIE\fP given by \f(CWownerdie\fP.  It returns
  470. the \f(CWDwarf_P_Attribute\fP descriptor representing this attribute
  471. on success.  On error, it returns \f(CWDW_DLV_BADADDR\fP.
  472.  
  473. .DS
  474. \f(CWDwarf_P_Attribute dwarf_add_AT_const_value_signedint(
  475.         Dwarf_P_Die ownerdie,
  476.         Dwarf_Signed signed_value,
  477.         Dwarf_Error *error)\fP
  478. .DE
  479. The function \f(CWdwarf_add_AT_const_value_signedint()\fP adds the
  480. given \f(CWDwarf_Signed\fP value \f(CWsigned_value\fP as the value
  481. of the \f(CWDW_AT_const_value\fP attribute for the \f(CWDIE\fP
  482. described by the given \f(CWownerdie\fP.  It returns the 
  483. \f(CWDwarf_P_Attribute\fP descriptor for this attribute on success.  
  484. On error, it returns \f(CWDW_DLV_BADADDR\fP.
  485.  
  486. .DS
  487. \f(CWDwarf_P_Attribute dwarf_add_AT_const_value_unsignedint(
  488.         Dwarf_P_Die ownerdie,
  489.         Dwarf_Unsigned unsigned_value,
  490.         Dwarf_Error *error)\fP
  491. .DE
  492. The function \f(CWdwarf_add_AT_const_value_unsignedint()\fP adds the
  493. given \f(CWDwarf_Unsigned\fP value \f(CWunsigned_value\fP as the value
  494. of the \f(CWDW_AT_const_value\fP attribute for the \f(CWDIE\fP described 
  495. by the given \f(CWownerdie\fP.  It returns the \f(CWDwarf_P_Attribute\fP
  496. descriptor for this attribute on success.  On error, it returns
  497. \f(CWDW_DLV_BADADDR\fP.
  498.  
  499. .DS
  500. \f(CWDwarf_P_Attribute dwarf_add_AT_const_value_string(
  501.         Dwarf_P_Die ownerdie,
  502.         char *string_value,
  503.         Dwarf_Error *error)\fP
  504. .DE
  505. The function \f(CWdwarf_add_AT_const_value_string()\fP adds the 
  506. string value given by \f(CWstring_value\fP as the value of the 
  507. \f(CWDW_AT_const_value\fP attribute for the \f(CWDIE\fP described 
  508. by the given \f(CWownerdie\fP.  It returns the \f(CWDwarf_P_Attribute\fP
  509. descriptor for this attribute on success.  On error, it returns
  510. \f(CWDW_DLV_BADADDR\fP.
  511.  
  512. .DS
  513. \f(CWDwarf_P_Attribute dwarf_add_AT_targ_address(
  514.         Dwarf_P_Debug dbg,
  515.         Dwarf_P_Die ownerdie,
  516.         Dwarf_Half attr,
  517.         Dwarf_Unsigned pc_value,
  518.         Dwarf_Signed sym_index,
  519.         Dwarf_Error *error)\fP
  520. .DE
  521. The function \f(CWdwarf_add_AT_targ_address()\fP adds an attribute that
  522. belongs to the "address" class to the die specified by \f(CWownerdie\fP.  
  523. The attribute is specified by \f(CWattr\fP, and the object that the 
  524. \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.  The relocatable 
  525. address that is the value of the attribute is specified by \f(CWpc_value\fP. 
  526. The symbol to be used for relocation is specified by the \f(CWsym_index\fP,
  527. which is the index of the symbol in the Elf symbol table.
  528.  
  529. It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
  530. on success, and \f(CWDW_DLV_BADADDR\fP on error.
  531.  
  532. .DS
  533. \f(CWDwarf_P_Attribute dwarf_add_AT_unsigned_const(
  534.         Dwarf_P_Debug dbg,
  535.         Dwarf_P_Die ownerdie,
  536.         Dwarf_Half attr,
  537.         Dwarf_Unsigned value,
  538.         Dwarf_Error *error)\fP
  539. .DE
  540. The function \f(CWdwarf_add_AT_unsigned_const()\fP adds an attribute
  541. with a \f(CWDwarf_Unsigned\fP value belonging to the "constant" class, 
  542. to the \f(CWDIE\fP specified by \f(CWownerdie\fP.  The object that
  543. the \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.  The attribute
  544. is specified by \f(CWattr\fP, and its value is specified by \f(CWvalue\fP.
  545.  
  546. It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
  547. on success, and \f(CWDW_DLV_BADADDR\fP on error.
  548.  
  549. .DS
  550. \f(CWDwarf_P_Attribute dwarf_add_AT_signed_const(
  551.         Dwarf_P_Debug dbg,
  552.         Dwarf_P_Die ownerdie,
  553.         Dwarf_Half attr,
  554.         Dwarf_Signed value,
  555.         Dwarf_Error *error)\fP
  556. .DE
  557. The function \f(CWdwarf_add_AT_signed_const()\fP adds an attribute
  558. with a \f(CWDwarf_Signed\fP value belonging to the "constant" class,
  559. to the \f(CWDIE\fP specified by \f(CWownerdie\fP.  The object that
  560. the \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.  The attribute
  561. is specified by \f(CWattr\fP, and its value is specified by \f(CWvalue\fP.
  562.  
  563. It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
  564. on success, and \f(CWDW_DLV_BADADDR\fP on error.
  565.  
  566. .DS
  567. \f(CWDwarf_P_Attribute dwarf_add_AT_reference(
  568.         Dwarf_P_Debug dbg,
  569.         Dwarf_P_Die ownerdie,
  570.         Dwarf_Half attr,
  571.         Dwarf_P_Die otherdie,
  572.         Dwarf_Error *error)\fP
  573. .DE
  574. The function \f(CWdwarf_add_AT_reference()\fP adds an attribute
  575. with a value that is a reference to another \f(CWDIE\fP in the
  576. compilation-unit to the \f(CWDIE\fP specified by \f(CWownerdie\fP.  
  577. The object that the \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.  
  578. The attribute is specified by \f(CWattr\fP, and the other \f(CWDIE\fP
  579. being referred to is specified by \f(CWotherdie\fP.
  580.  
  581. It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
  582. on success, and \f(CWDW_DLV_BADADDR\fP on error.
  583.  
  584. .DS
  585. \f(CWDwarf_P_Attribute dwarf_add_AT_flag(
  586.         Dwarf_P_Debug dbg,
  587.         Dwarf_P_Die ownerdie,
  588.         Dwarf_Half attr,
  589.         Dwarf_Small flag,
  590.         Dwarf_Error *error)\fP
  591. .DE
  592. The function \f(CWdwarf_add_AT_flag()\fP adds an attribute with 
  593. a \f(CWDwarf_Small\fP value belonging to the "flag" class, to the 
  594. \f(CWDIE\fP specified by \f(CWownerdie\fP.  The object that the 
  595. \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.  The attribute
  596. is specified by \f(CWattr\fP, and its value is specified by \f(CWflag\fP.
  597.  
  598. It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
  599. on success, and \f(CWDW_DLV_BADADDR\fP on error.
  600.  
  601. .DS
  602. \f(CWDwarf_P_Attribute dwarf_add_AT_string(
  603.         Dwarf_P_Debug dbg,
  604.         Dwarf_P_Die ownerdie,
  605.         Dwarf_Half attr,
  606.         char *string,
  607.         Dwarf_Error *error)\fP
  608. .DE
  609. The function \f(CWdwarf_add_AT_string()\fP adds an attribute with a 
  610. value that is a character string to the \f(CWDIE\fP specified by 
  611. \f(CWownerdie\fP.  The object that the \f(CWDIE\fP belongs to is 
  612. specified by \f(CWdbg\fP.  The attribute is specified by \f(CWattr\fP, 
  613. and its value is pointed to by \f(CWstring\fP.
  614.  
  615. It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
  616. on success, and \f(CWDW_DLV_BADADDR\fP on error.
  617.  
  618. .H 2 "Expression Creation"
  619. The following functions are used to convert location expressions into
  620. blocks so that attributes with values that are location expressions
  621. can store their values as a \f(CWDW_FORM_blockn\fP value.  This is for 
  622. both .debug_info and .debug_loc expression blocks.
  623.  
  624. To create an expression, first call \f(CWdwarf_new_expr()\fP to get 
  625. a \f(CWDwarf_P_Expr\fP descriptor that can be used to build up the
  626. block containing the location expression.  Then insert the parts of 
  627. the expression in prefix order (exactly the order they would be 
  628. interpreted in in an expression interpreter).  The bytes of the 
  629. expression are then built-up as specified by the user.
  630.  
  631. .DS
  632. \f(CWDwarf_Expr dwarf_new_expr(
  633.         Dwarf_P_Debug dbg,
  634.         Dwarf_Error *error)\fP
  635. .DE
  636. The function \f(CWdwarf_new_expr()\fP creates a new expression area 
  637. in which a location expression stream can be created.  It returns
  638. a \f(CWDwarf_P_Expr\fP descriptor that can be used to add operators
  639. to build up a location expression.  It returns \f(CWNULL\fP on error.
  640.  
  641. .DS
  642. \f(CWDwarf_Unsigned dwarf_add_expr_gen(
  643.         Dwarf_P_Expr expr,
  644.         Dwarf_Small opcode, 
  645.         Dwarf_Unsigned val1,
  646.         Dwarf_Unsigned val2,
  647.         Dwarf_Error *error)\fP
  648. .DE
  649. The function \f(CWdwarf_add_expr_gen()\fP takes an operator specified
  650. by \f(CWopcode\fP, along with up to 2 operands specified by \f(CWval1\fP,
  651. and \f(CWval2\fP, converts it into the \f(CWDwarf\fP representation and 
  652. appends the bytes to the byte stream being assembled for the location
  653. expression represented by \f(CWexpr\fP.  The first operand, if present,
  654. to \f(CWopcode\fP is in \f(CWval1\fP, and the second operand, if present,
  655. is in \f(CWval2\fP.  Both the operands may actually be signed or unsigned
  656. depending on \f(CWopcode\fP.  It returns the number of bytes in the byte
  657. stream for \f(CWexpr\fP currently generated, i.e. after the addition of
  658. \f(CWopcode\fP.  It returns \f(CWDW_DLV_NOCOUNT\fP on error.
  659.  
  660. The function \f(CWdwarf_add_expr_gen()\fP works for all opcodes except
  661. those that have a target address as an operand.  This is because it does
  662. not set up a relocation record that is needed when target addresses are
  663. involved.
  664.  
  665. .DS
  666. \f(CWDwarf_Unsigned dwarf_add_expr_addr(
  667.         Dwarf_P_Expr expr,
  668.         Dwarf_Unsigned address,
  669.         Dwarf_Signed sym_index,
  670.         Dwarf_Error *error)\fP 
  671. .DE
  672. The function \f(CWdwarf_add_expr_addr()\fP is used to add the
  673. \f(CWDW_OP_addr\fP opcode to the location expression represented
  674. by the given \f(CWDwarf_P_Expr\fP descriptor, \f(CWexpr\fP.  The
  675. value of the relocatable address is given by \f(CWaddress\fP.  
  676. The symbol to be used for relocation is given by \f(CWsym_index\fP,
  677. which is the index of the symbol in the Elf symbol table.  It returns 
  678. the number of bytes in the byte stream for \f(CWexpr\fP currently 
  679. generated, i.e. after the addition of the \f(CWDW_OP_addr\fP operator.  
  680. It returns \f(CWDW_DLV_NOCOUNT\fP on error.
  681.  
  682. .DS
  683. \f(CWDwarf_Unsigned dwarf_expr_current_offset(
  684.         Dwarf_P_Expr expr, 
  685.         Dwarf_Error *error)\fP
  686. .DE
  687. The function \f(CWdwarf_expr_current_offset()\fP returns the number
  688. of bytes currently in the byte stream for the location expression
  689. represented by the given \fCW(Dwarf_P_Expr\fP descriptor, \f(CWexpr\fP.
  690. It returns \f(CWDW_DLV_NOCOUNT\fP on error.
  691.  
  692. .DS
  693. \f(CWDwarf_Addr dwarf_expr_into_block(
  694.         Dwarf_P_Expr expr,
  695.         Dwarf_Unsigned *length,
  696.         Dwarf_Error *error)\fP 
  697. .DE
  698. The function \f(CWdwarf_expr_into_block()\fP returns the address
  699. of the start of the byte stream generated for the location expression
  700. represented by the given \f(CWDwarf_P_Expr\fP descriptor, \f(CWexpr\fP.
  701. The length of the byte stream is returned in the location pointed to
  702. by \f(CWlength\fP.  It returns \f(CWDW_DLV_BADADDR\fP on error.
  703.  
  704. .H 2 "Line Number Operations"
  705. These are operations on the .debug_line section.  They provide 
  706. information about instructions in the program and the source 
  707. lines the instruction come from.  Typically, code is generated 
  708. in contiguous blocks, which may then be relocated as contiguous 
  709. blocks.  To make the provision of relocation information more 
  710. efficient, the information is recorded in such a manner that only
  711. the address of the start of the block needs to be relocated.  
  712. This is done by providing the address of the first instruction 
  713. in a block using the function \f(CWdwarf_lne_set_address()\fP.  
  714. Information about the instructions in the block are then added 
  715. using the function \f(CWdwarf_add_line_entry()\fP, which specifies
  716. offsets from the address of the first instruction.  The end of 
  717. a contiguous block is indicated by calling the function 
  718. \f(CWdwarf_lne_end_sequence()\fP.
  719.  
  720. .DS
  721. \f(CWDwarf_Unsigned dwarf_add_line_entry(
  722.         Dwarf_P_Debug dbg,
  723.         Dwarf_Unsigned file_index, 
  724.         Dwarf_Addr code_offset,
  725.         Dwarf_Unsigned lineno, 
  726.         Dwarf_Signed column_number,
  727.         Dwarf_Bool is_source_stmt_begin, 
  728.         Dwarf_Bool is_basic_block_begin,
  729.         Dwarf_Error *error)\fP
  730. .DE
  731. The function \f(CWdwarf_add_line_entry()\fP adds an entry to the
  732. section containing information about source lines.  It specifies
  733. in \f(CWcode_offset\fP, the offset from the address set using
  734. \f(CWdwarfdwarf_lne_set_address()\fP, of the address of the first
  735. instruction in a contiguous block.  The source file that gave rise
  736. to the instruction is specified by \f(CWfile_index\fP, the source
  737. line number is specified by \f(CWlineno\fP, and the source column 
  738. number is specified by \f(CWcolumn_number\fP.  \f(CWfile_index\fP 
  739. is the index of the source file in a list of source files which is 
  740. built up using the function \f(CWdwarf_add_file_decl()\fP. 
  741.  
  742. \f(CWis_source_stmt_begin\fP is a boolean flag that is true only if 
  743. the instruction at \f(CWcode_address\fP is the first instruction in 
  744. the sequence generated for the source line at \f(CWlineno\fP.  Similarly,
  745. \f(CWis_basic_block_begin\fP is a boolean flag that is true only if
  746. the instruction at \f(CWcode_address\fP is the first instruction of
  747. a basic block.
  748.  
  749. It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error.
  750.  
  751. .DS
  752. \f(CWDwarf_Unsigned dwarf_lne_set_address(
  753.         Dwarf_P_Debug dbg,
  754.         Dwarf_Addr offs,
  755.         Dwarf_Unsigned symidx,
  756.         Dwarf_Error *error)\fP
  757. .DE
  758. The function \f(CWdwarf_lne_set_address()\fP sets the target address
  759. at which a contiguous block of instructions begin.  Information about
  760. the instructions in the block is added to .debug_line using calls to
  761. \f(CWdwarfdwarf_add_line_entry()\fP which specifies the offset of each
  762. instruction in the block relative to the start of the block.  This is 
  763. done so that a single relocation record can be used to obtain the final
  764. target address of every instruction in the block.
  765.  
  766. The relocatable address of the start of the block of instructions is
  767. specified by \f(CWoffs\fP.  The symbol used to relocate the address 
  768. is given by \f(CWsymidx\fP, which is the index of the symbol in the
  769. Elf symbol table.  
  770.  
  771. It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error.
  772.  
  773. .DS
  774. \f(CWDwarf_Unsigned dwarf_lne_end_sequence(
  775.         Dwarf_P_Debug dbg,
  776.         Dwarf_Error *error)\fP
  777. .DE
  778. The function \f(CWdwarf_lne_end_sequence()\fP indicates the end of a
  779. contiguous block of instructions.  To add information about another
  780. block of instructions, a call to \f(CWdwarf_lne_set_address()\fP will 
  781. have to be made to set the address of the start of the target address
  782. of the block, followed by calls to \f(CWdwarf_add_line_entry()\fP for
  783. each of the instructions in the block.
  784.  
  785. It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error.
  786.  
  787. .DS
  788. \f(CWDwarf_Unsigned dwarf_add_directory_decl(
  789.         Dwarf_P_Debug dbg,
  790.         char *name,
  791.         Dwarf_Error *error)\fP
  792. .DE
  793. The function \f(CWdwarf_add_directory_decl()\fP adds the string 
  794. specified by \f(CWname\fP to the list of include directories in 
  795. the statement program prologue of the .debug_line section.  The
  796. string should therefore name a directory from which source files
  797. have been used to create the present object.
  798.  
  799. It returns the index of the string just added, in the list of include 
  800. directories for the object.  This index is then used to refer to this 
  801. string.  It returns \f(CWDW_DLV_NOCOUNT\fP on error.
  802.  
  803. .DS
  804. \f(CWDwarf_Unsigned dwarf_add_file_decl(
  805.         Dwarf_P_Debug dbg,
  806.         char *name,
  807.         Dwarf_Unsigned dir_idx,
  808.         Dwarf_Unsigned time_mod,
  809.         Dwarf_Unsigned length,
  810.         Dwarf_Error *error)\fP
  811. .DE
  812. The function \f(CWdwarf_add_file_decl()\fP adds the name of a source
  813. file that contributed to the present object.  The name of the file is
  814. specified by \f(CWname\fP.  In case the name is not a fully-qualified
  815. pathname, it is prefixed with the name of the directory specified by
  816. \f(CWdir_idx\fP.  \f(CWdir_idx\fP is the index of the directory to be
  817. prefixed in the list builtup using \f(CWdwarf_add_directory_decl()\fP.
  818.  
  819. \f(CWtime_mod\fP gives the time at which the file was last modified,
  820. and \f(CWlength\fP gives the length of the file in bytes.
  821.  
  822. It returns the index of the source file in the list built up so far
  823. using this function, on success.  This index can then be used to 
  824. refer to this source file in calls to \f(CWdwarf_add_line_entry()\fP.
  825. On error, it returns \f(CWDW_DLV_NOCOUNT\fP.
  826.  
  827. .H 2 "Fast Access (aranges) Operations"
  828. These functions operate on the .debug_aranges section.  
  829.  
  830. .DS
  831. \f(CWDwarf_Unsigned dwarf_add_arange(
  832.         Dwarf_P_Debug dbg,
  833.         Dwarf_Addr begin_address,
  834.         Dwarf_Unsigned length,
  835.         Dwarf_Signed symbol_index,
  836.         Dwarf_Error *error)\fP
  837. .DE
  838. The function \f(CWdwarf_add_arange()\fP adds another address range 
  839. to be added to the section containing address range information, 
  840.   .debug_aranges.  The relocatable start address of the range is 
  841. specified by \f(CWbegin_address\fP, and the length of the address 
  842. range is specified by \f(CWlength\fP.  The relocatable symbol to be 
  843. used to relocate the start of the address range is specified by 
  844. \f(CWsymbol_index\fP, which is the index of the symbol in the Elf
  845. symbol table.
  846.  
  847. It returns a non-zero value on success, and \f(CW0\fP on error.
  848.  
  849. .H 2 "Fast Access (pubnames) Operations"
  850. These functions operate on the .debug_pubnames section.
  851.  
  852. .DS
  853. \f(CWDwarf_Unsigned dwarf_add_pubname(
  854.         Dwarf_P_Debug dbg,
  855.         Dwarf_P_Die die,
  856.         char *pubname_name,
  857.         Dwarf_Error *error)\fP
  858. .DE
  859. The function \f(CWdwarf_add_pubname()\fP adds the pubname specified
  860. by \f(CWpubname_name\fP to the section containing pubnames, i.e.
  861.   .debug_pubnames.  The \f(CWDIE\fP that represents the function
  862. being named is specified by \f(CWdie\fP.  
  863.  
  864. It returns a non-zero value on success, and \f(CW0\fP on error.
  865.  
  866. .H 2 "Fast Access (weak names) Operations"
  867. These functions operate on the .debug_weaknames section.
  868.  
  869. .DS
  870. \f(CWDwarf_Unsigned dwarf_add_weakname(
  871.         Dwarf_P_Debug dbg,
  872.         Dwarf_P_Die die,
  873.         char *weak_name,
  874.         Dwarf_Error *error)\fP
  875. .DE
  876. The function \f(CWdwarf_add_weakname()\fP adds the weak name specified
  877. by \f(CWweak_name\fP to the section containing weak names, i.e.  
  878.  .debug_weaknames.  The \f(CWDIE\fP that represents the function
  879. being named is specified by \f(CWdie\fP.  
  880.  
  881. It returns a non-zero value on success, and \f(CW0\fP on error.
  882.  
  883. .H 2 "Static Function Names Operations"
  884. The .debug_funcnames section contains the names of static function 
  885. names defined in the object, and also the offsets of the \f(CWDIE\fPs
  886. that represent the definitions of the functions in the .debug_info 
  887. section.
  888.  
  889. .DS
  890. \f(CWDwarf_Unsigned dwarf_add_funcname(
  891.         Dwarf_P_Debug dbg,
  892.         Dwarf_P_Die die,
  893.         char *func_name,
  894.         Dwarf_Error *error)\fP
  895. .DE
  896. The function \f(CWdwarf_add_funcname()\fP adds the name of a static
  897. function specified by \f(CWfunc_name\fP to the section containing the
  898. names of static functions defined in the object represented by \f(CWdbg\fP.
  899. The \f(CWDIE\fP that represents the definition of the function is
  900. specified by \f(CWdie\fP.
  901.  
  902. It returns a non-zero value on success, and \f(CW0\fP on error.
  903.  
  904. .H 2 "File-scope User-defined Type Names Operations"
  905. The .debug_typenames section contains the names of file-scope
  906. user-defined types in the given object, and also the offsets 
  907. of the \f(CWDIE\fPs that represent the definitions of the types 
  908. in the .debug_info section.
  909.  
  910. .DS
  911. \f(CWDwarf_Unsigned dwarf_add_typename(
  912.         Dwarf_P_Debug dbg,
  913.         Dwarf_P_Die die,
  914.         char *type_name,
  915.         Dwarf_Error *error)\fP
  916. .DE
  917. The function \f(CWdwarf_add_typename()\fP adds the name of a file-scope
  918. user-defined type specified by \f(CWtype_name\fP to the section that 
  919. contains the names of file-scope user-defined type.  The object that 
  920. this section belongs to is specified by \f(CWdbg\fP.  The \f(CWDIE\fP 
  921. that represents the definition of the type is specified by \f(CWdie\fP.
  922.  
  923. It returns a non-zero value on success, and \f(CW0\fP on error.
  924.  
  925. .H 2 "File-scope Static Variable Names Operations"
  926. The .debug_varnames section contains the names of file-scope static
  927. variables in the given object, and also the offsets of the \f(CWDIE\fPs
  928. that represent the definition of the variables in the .debug_info
  929. section.
  930.  
  931. .DS
  932. \f(CWDwarf_Unsigned dwarf_add_varname(
  933.         Dwarf_P_Debug dbg,
  934.         Dwarf_P_Die die,
  935.         char *var_name,
  936.         Dwarf_Error *error)\fP
  937. .DE
  938. The function \f(CWdwarf_add_varname()\fP adds the name of a file-scope
  939. static variable specified by \f(CWvar_name\fP to the section that 
  940. contains the names of file-scope static variables defined by the 
  941. object represented by \f(CWdbg\fP.  The \f(CWDIE\fP that represents
  942. the definition of the static variable is specified by \f(CWdie\fP.
  943.  
  944. It returns a non-zero value on success, and \f(CW0\fP on error.
  945.  
  946. .H 2 "Macro Information Creation"
  947. All strings passed in by the caller are copied by these
  948. functions, so the space in which the caller provides the strings
  949. may be ephemeral (on the stack, or immediately reused or whatever)
  950. without this causing any difficulty.
  951. .DS
  952. \f(CWint dwarf_def_macro(Dwarf_P_Debug dbg,
  953.     Dwarf_Unsigned lineno,
  954.     char *name
  955.     char *value,
  956.         Dwarf_Error *error);\fP
  957. .DE
  958. Adds a macro definition.
  959. The \f(CWname\fP argument should include the parentheses
  960. and parameter names if this is a function-like macro.
  961. Neither string should contain extraneous whitespace.
  962. \f(CWdwarf_def_macro()\fP adds the mandated space after the
  963. name and before the value  in the
  964. output DWARF section(but does not change the
  965. strings pointed to by the arguments).
  966. If this is a definition before any files are read,
  967. \f(CWlineno\fP should be 0.
  968. Returns \f(CWDW_DLV_ERROR\fP
  969. and sets \f(CWerror\fP
  970. if there is an error.
  971. Returns \f(CWDW_DLV_OK\fP if the call was successful.
  972. .DS
  973. \f(CWint dwarf_undef macro(Dwarf_P_Debug dbg,
  974.     Dwarf_Unsigned lineno,
  975.     char *name,
  976.         Dwarf_Error *error);\fP
  977. .DE
  978. Adds a macro un-definition note.
  979. If this is a definition before any files are read,
  980. \f(CWlineno\fP should be 0.
  981. Returns \f(CWDW_DLV_ERROR\fP
  982. and sets \f(CWerror\fP
  983. if there is an error.
  984. Returns \f(CWDW_DLV_OK\fP if the call was successful.
  985. .DS
  986. \f(CWint dwarf_start_macro_file(Dwarf_P_Debug dbg,
  987.     Dwarf_Unsigned lineno,
  988.         Dwarf_Unsigned fileindex,
  989.         Dwarf_Error *error);\fP
  990. .DE
  991. \f(CWfileindex\fP is an index in the .debug_line header: 
  992. the index of
  993. the file name.
  994. See the function \f(CWdwarf_add_file_decl()\fP.
  995. The \f(CWlineno\fP should be 0 is this file is
  996. the file of the compilation unit source itself
  997. (which, of course, is not a #include in any
  998. file).
  999. Returns \f(CWDW_DLV_ERROR\fP
  1000. and sets \f(CWerror\fP
  1001. if there is an error.
  1002. Returns \f(CWDW_DLV_OK\fP if the call was successful.
  1003. .DS
  1004. \f(CWint dwarf_end_macro_file(Dwarf_P_Debug dbg,
  1005.         Dwarf_Error *error);\fP
  1006. .DE
  1007. Returns \f(CWDW_DLV_ERROR\fP
  1008. and sets \f(CWerror\fP
  1009. if there is an error.
  1010. Returns \f(CWDW_DLV_OK\fP if the call was successful.
  1011. .DS
  1012. \f(CWint dwarf_vendor_ext(Dwarf_P_Debug dbg,
  1013.     Dwarf_Unsigned constant,
  1014.     char *         string,
  1015.     Dwarf_Error*   error); \fP
  1016. .DE
  1017. The meaning of the \f(CWconstant\fP and the\f(CWstring\fP
  1018. are undefined by DWARF itself, but the string must be
  1019. an ordinary null terminated string.
  1020. Returns \f(CWDW_DLV_ERROR\fP
  1021. and sets \f(CWerror\fP
  1022. if there is an error.
  1023. Returns \f(CWDW_DLV_OK\fP if the call was successful.
  1024. .H 2 "Low Level (.debug_frame) operations"
  1025. These functions operate on the .debug_frame section.  Refer to 
  1026. \fIlibdwarf.h\fP for the register names and register assignment 
  1027. mapping.  Both of these are necessarily machine dependent.
  1028.  
  1029. .DS
  1030. \f(CWDwarf_P_Fde dwarf_new_fde(
  1031.         Dwarf_P_Debug dbg, 
  1032.         Dwarf_Error *error)\fP
  1033. .DE
  1034. The function \f(CWdwarf_new_fde()\fP returns a new \f(CWDwarf_P_Fde\fP
  1035. descriptor that should be used to build a complete \f(CWFDE\fP.  
  1036. Subsequent calls to routines that build up the \f(CWFDE\fP should use
  1037. the same \f(CWDwarf_P_Fde\fP descriptor.
  1038.  
  1039. It returns a valid \f(CWDwarf_P_Fde\fP descriptor on success, and
  1040. \f(CWDW_DLV_BADADDR\fP on error.
  1041.  
  1042. .DS
  1043. \f(CWDwarf_Unsigned dwarf_add_frame_cie(
  1044.         Dwarf_P_Debug dbg,
  1045.         char *augmenter, 
  1046.         Dwarf_Small code_align,
  1047.         Dwarf_Small data_align, 
  1048.         Dwarf_Small ret_addr_reg, 
  1049.         Dwarf_Ptr init_bytes, 
  1050.         Dwarf_Unsigned init_bytes_len,
  1051.         Dwarf_Error *error);\fP
  1052. .DE
  1053. The function \f(CWdwarf_add_frame_cie()\fP creates a \f(CWCIE\fP,
  1054. and returns an index to it, that should be used to refer to this
  1055. \f(CWCIE\fP.  \f(CWCIE\fPs are used by \f(CWFDE\fPs to setup
  1056. initial values for frames.  The augmentation string for the \f(CWCIE\fP
  1057. is specified by \f(CWaugmenter\fP.  The code alignement factor,
  1058. data alignment factor, and the return address register for the
  1059. \f(CWCIE\fP are specified by \f(CWcode_align\fP, \f(CWdata_align\fP,
  1060. and \f(CWret_addr_reg\fP respectively.  \f(CWinit_bytes\fP points
  1061. to the bytes that represent the instructions for the \f(CWCIE\fP
  1062. being created, and \f(CWinit_bytes_len\fP specifies the number
  1063. of bytes of instructions.
  1064.  
  1065. It returns an index to the \f(CWCIE\fP just created on success.
  1066. On error it returns \f(CWDW_DLV_NOCOUNT\fP.
  1067.  
  1068. .DS
  1069. \f(CWDwarf_Unsigned dwarf_add_frame_fde(
  1070.         Dwarf_P_Debug dbg,
  1071.         Dwarf_P_Fde fde,
  1072.         Dwarf_P_Die die,
  1073.         Dwarf_Unsigned cie,
  1074.         Dwarf_Addr virt_addr,
  1075.         Dwarf_Unsigned  code_len,
  1076.         Dwarf_Unsigned sym_idx,
  1077.         Dwarf_Error* error)\fP
  1078. .DE
  1079. The function \f(CWdwarf_add_frame_fde()\fP adds the \f(CWFDE\fP
  1080. specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the
  1081. object represented by the given \f(CWdbg\fP.  \f(CWdie\fP specifies
  1082. the \f(CWDIE\fP that represents the function whose frame information
  1083. is specified by the given \f(CWfde\fP.  \f(CWcie\fP specifies the
  1084. index of the \f(CWCIE\fP that should be used to setup the initial
  1085. conditions for the given frame.  \f(CWvirt_addr\fP represents the
  1086. relocatable address at which the code for the given function begins,
  1087. and \f(CWsym_idx\fP gives the index of the relocatable symbol to
  1088. be used to relocate this address (\f(CWvirt_addr\fP that is).
  1089. \f(CWcode_len\fP specifies the size in bytes of the machine instructions
  1090. for the given function.
  1091.  
  1092. It returns an index to the given \f(CWfde\fP.
  1093.  
  1094. .DS
  1095. \f(CWDwarf_Unsigned dwarf_add_frame_info(
  1096.         Dwarf_P_Debug dbg,
  1097.         Dwarf_P_Fde fde,
  1098.         Dwarf_P_Die die,
  1099.         Dwarf_Unsigned cie,
  1100.         Dwarf_Addr virt_addr,
  1101.         Dwarf_Unsigned  code_len,
  1102.         Dwarf_Unsigned sym_idx,
  1103.     Dwarf_Signed offset_into_exception_tables,
  1104.     Dwarf_Unsigned exception_table_symbol,
  1105.         Dwarf_Error* error)\fP
  1106. .DE
  1107. The function \f(CWdwarf_add_frame_fde()\fP adds the \f(CWFDE\fP
  1108. specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the
  1109. object represented by the given \f(CWdbg\fP.  \f(CWdie\fP specifies
  1110. the \f(CWDIE\fP that represents the function whose frame information
  1111. is specified by the given \f(CWfde\fP.  \f(CWcie\fP specifies the
  1112. index of the \f(CWCIE\fP that should be used to setup the initial
  1113. conditions for the given frame.  \f(CWvirt_addr\fP represents the
  1114. relocatable address at which the code for the given function begins,
  1115. and \f(CWsym_idx\fP gives the index of the relocatable symbol to
  1116. be used to relocate this address (\f(CWvirt_addr\fP that is).
  1117. \f(CWcode_len\fP specifies the size in bytes of the machine instructions
  1118. for the given function. \f(CWoffset_into_exception_tables\fP specifies the
  1119. offset into \f(CW.MIPS.eh_region\fP elf section where the exception tables 
  1120. for this function begins. \f(CWexception_table_symbol\fP  gives the index of 
  1121. the relocatable symbol to be used to relocate this offset.
  1122.  
  1123. It returns an index to the given \f(CWfde\fP.
  1124.  
  1125. .DS
  1126. \f(CWDwarf_P_Fde dwarf_fde_cfa_offset(
  1127.         Dwarf_P_Fde fde,
  1128.         Dwarf_Unsigned reg,
  1129.         Dwarf_Signed offset,
  1130.         Dwarf_Error *error)\fP
  1131. .DE
  1132. The function \f(CWdwarf_fde_cfa_offset()\fP appends a \f(CWDW_CFA_offset\fP
  1133. operation to the \f(CWFDE\fP, specified by \f(CWfde\fP,  being constructed.  
  1134. The first operand of the \f(CWDW_CFA_offset\fP operation is specified by 
  1135. \f(CWreg\P.  The register specified should not exceed 6 bits.  The second 
  1136. operand of the \f(CWDW_CFA_offset\fP operation is specified by \f(CWoffset\fP.
  1137.  
  1138. It returns the given \f(CWfde\fP on success, and \f(CWDW_DLV_BADADDR\fP
  1139. on error.
  1140.  
  1141. .DS
  1142. \f(CWDwarf_P_Fde dwarf_add_fde_inst(
  1143.         Dwarf_P_Fde fde,
  1144.         Dwarf_Small op,
  1145.         Dwarf_Unsigned val1,
  1146.         Dwarf_Unsigned val2,
  1147.         Dwarf_Error *error)\fP
  1148. .DE
  1149. The function \f(CWdwarf_add_fde_inst()\fP adds the operation specified
  1150. by \f(CWop\fP to the \f(CWFDE\fP specified by \f(CWfde\fP.  Upto two
  1151. operands can be specified in \f(CWval1\fP, and \f(CWval2\fP.  Based on
  1152. the operand specified \f(CWLibdwarf\fP decides how many operands are
  1153. meaningful for the operand.  It also converts the operands to the 
  1154. appropriate datatypes even they are passed to \f(CWdwarf_add_fde_inst\fP
  1155. as \f(CWDwarf_Unsigned\fP.
  1156.  
  1157. It returns the given \f(CWfde\fP on success, and \f(CWDW_DLV_BADADDR\fP
  1158. on error.
  1159.  
  1160. .S
  1161. .TC
  1162. .CS
  1163.